Network CD 1/Network CD.iso/fredfish/841-850/ff848/cweb/readme.c89

Text File | 1993-03-31 | 9.7 KB | 217 lines

                            -*-Text-*-
% This file, README.C89, is part of CWEB-p.
% The CWEB programs by Silvio Levy are based on programs by D. E. Knuth.
% ANSI-C conforming changes and Turbo-C++ implementation are made by
% Hans-Hermann Bode <[e-mail] or
% [e-mail]>, additional support for other
% ANSI-C compilers (e.g. c89) provided by Klaus Guntermann
% <[e-mail]>.
% The programs are distributed WITHOUT ANY WARRANTY, express or implied.
% This readme file last updated September 1992 by Hans-Hermann Bode.

% Copyright (C) 1987,1990,1992 Silvio Levy and Donald E. Knuth
% Copyright (C) 1991,1992 Hans-Hermann Bode
% Copyright (C) 1992 Klaus Guntermann

% Permission is granted to make and distribute verbatim copies of this
% document provided that the copyright notice and this permission notice
% are preserved on all copies.

% Permission is granted to copy and distribute modified versions of this
% document under the conditions for verbatim copying, provided that the
% entire resulting derived work is distributed under the terms of a
% permission notice identical to this one.

% Please send comments, suggestions, etc. concerning to the original CWEB to
% [e-mail].
% Send suggestions and complaints concerning to the ANSI-C/Turbo-C++
% implementation to [e-mail].

This is the ANSI-C/Turbo-C++ implementation of Silvio Levy's and
Donald E. Knuth's CWEB system, compiled and provided with changefiles
for ANSI C and Turbo C++ and a makefile for Turbo Make by
Hans-Hermann Bode, including additional changes to improve support of
ANSI-C compilers and a makefile for c89 by Klaus Guntermann. Note
that the changes for the Turbo-C++ compiler are made conditional
(they will become effective only if the symbol __TURBOC__ is defined,
which automatically is the case when compiled with Turbo C++), so
users of other systems with ANSI-C compilers might be able to compile
the sources without editing.

This directory contains the following files from the original CWEB
distribution:

./makefile.org        makefile from the original distribution
./readme.org        readme file from the original distribution
./common.h        header file to be included in ctangle.w and cweave.w
./common.w        common code for ctangle and cweave
./ctangle.w        the tangle processor
./cweave.w        the weave processor
./cweb.1        manual page (nroff format)
./cweb.el        elisp file for GNU Emacs
./cwebmac.tex        macros for formatting
./cwebman.tex        the user manual
./prod.w        production rules to be included in cweave.w
./examples        directory containing examples of CWEB programming
./examples/wc.w        - UNIX word-count utility
./examples/treeprin.w    - tree-structured directory lister by Norman Ramsey
./examples/wmerge.w    - WEB-like file merger by Silvio Levy
./examples/extex.w    - spellchecking filter for TeX and CWEB by Don Knuth
./examples/wordtest.w    - spellchecker by Don Knuth
./examples/xlib_typ.w    - include file for XView programs
./examples/xview_ty.w    - ditto
./examples/kspell.el    - Emacs interface to extex/wordtest
./examples/makefile    - generic makefile for CWEB applications
./examples/readme    - readme file from the examples directory

Note that the changefiles provided in the original distribution for vms are
removed here.

The following files are added in this distribution:

general:
./cweb.man        manual page (ASCII format)
./common-p.hch        change file for common.h
./common-p.ch        change file for common.w
./ctangl-p.ch        change file for ctangle.w
./cweave-p.ch        change file for cweave.w
./prod-p.ch        change file for prod.w
./ccwebmac.ch        change file for cwebmac.tex (including C++ macros)
./common-p.h        WMERGEd product of common.h and common-p.hch
./prod-p.w        WMERGEd product of prod.w and prod-p.ch
./ccwebmac.tex        WMERGEd product of cwebmac.tex and ccwebmac.ch
./common.c        CTANGLEd product of common.w and common-p.ch
./ctangle.c        CTANGLEd product of ctangle.w and ctangl-p.ch
./examples/wmerge-p.ch    change file for wmerge.w
./examples/wmerge.c    CTANGLEd product of wmerge.w and wmerge-p.ch

special for users of c89 or other ANSI C compilers:
./makefile.c89        makefile for c89
./readme.c89        this file for users of c89

special for PC users:
./readme.pc        informations for PC users
./makefile.pc        makefile for Turbo C++
./ctangle.exe        executable tangle processor, ANSI-C/Turbo-C++ version
./cweave.exe        executable weave processor, ANSI-C/Turbo-C++ version
./wmerge.exe        executable WEB merge program, from examples directory

Please note that most examples have not been converted to ANSI C yet.

The additional files with extensions .h, .w, .tex, and .c are
reproducable from the other sources by means of an executable WMERGE,
CTANGLE, and an ANSI-C compiler.

Before starting, you should run cwebman.tex (needs cwebmac.tex!)
through TeX and print out the manual.
If you are not going to use this distribution on a PC, you can
reclaim some disk space by removing all PC related files. You will have
to compile the binaries using your ANSI-C compiler.

Make sure, that the files you got are in proper format (if you
took them from a ZIP archive, line ends might still contain carriage
return and linefeed characters, which may not be appropriate for your
operating system).


How to create the binaries:

1. Rename the makefile.c89 to Makefile, for use with make.
Note that makefile.org is lacking some dependencies, so better start
from makefile.c89 when on a Un*x system.

2. If your compiler is not named c89, you have to change the CC
definition to the proper call in the Makefile, e.g. for the
ANSI-C version of gcc use
    CC = gcc -ansi
Check also the other lines in Makefile so that all directory
definitions are set properly for your local system and configuration.

3. Touch common.c, ctangle.c, and examples/wmerge.c to make them
up-to-date. To make ctangle, cweave and the wmerge processor say
`make all'; this should  produce actions similar to the following,
possibly with harmless warning messages from the compiler, and e.g.
the options and the name of the compiler may be as modified in
Makefile:

c89 -DDEBUG -DSTAT -c ctangle.c
c89 -DDEBUG -DSTAT -c common.c
c89 -DDEBUG -DSTAT -o ctangle ctangle.o common.o
./ctangle cweave cweave-p.ch
c89 -DDEBUG -DSTAT -c cweave.c
c89 -DDEBUG -DSTAT -o cweave cweave.o common.o
(cd examples; c89 -DDEBUG -DSTAT -o wmerge wmerge.c)

To get some reassurance that things are OK, you can say `make
cautiously', which ensures that CTANGLE will reproduce itself.
(Otherwise the source files common.w and ctangle.w won't actually
have been used.)

To install cweave, ctangle, wmerge, ccwebmac.tex, the manual page,
and an emacs macro file, say `make install'. You may also decide to
move the files manually to their proper places. See the Makefile for
details, what to move, and for suggestions, where to move it.

Incidentally, if you try the recompilation with another compiler, you
may have no luck without changing the sources. In this case, it is
necessary to do all the required changes in the .c file first, until
you can compile ctangle.c and common.c. But it is necessary then, to
add the same modifications to the change file. Finally processing
ctangle.w and the extended change file for ctangle with the modified
ctangle will create the same contents as the manual modifications.
If such changes are needed for a common compiler, please notify the
authors about this and send the extended changes.

4. Do not edit one of the .w files under any circumstances. Do all
modifications in the associated .ch files, but keep in mind that
you'll need a working ctangle processor to generate the updated .c
files.
Furthermore, do not edit common.h, prod.w, or cwebmac.tex. Make your
modifications to common-p.hch, prod-p.ch, or ccwebmac.ch instead. To
incorporate the changes you will need a working wmerge program. This
will be prepared when ctangle and cweave are created. There is a
tangled wmerge.c also in case you don't have a working ctangle
processor so far.

5. If you want a full documentation of the tangle and weave programs,
type `make doc'. The documentation created will include the changes
needed for the ANSI-C/C++ extensions.

6. To delete all intermediate files created in the make processes say
`make clean'.

7. The weave and tangle processors now recognize a CWEBINCLUDE
environment variable if common.c is compiled with INCLUDEDIR defined
(which is the default in makefile.c89). When an include file (@i
command) cannot be found in the current or given directory, its name
(completely as given!) is prefixed by the contents of CWEBINCLUDE and
a second try is made. A multi-path search is not supported yet, i.e.,
CWEBINCLUDE---if not empty---must contain a single path name and must
end with a `/'. Example in (Bourne-)sh or ksh:

    CWEBINCLUDE=/usr/local/lib/cweb/
    export CWEBINCLUDE

Furthermore, the file name in an @i command should never indicate an
absolute path, otherwise the mechanism described above will not work.

8. The tangle and weave processors of this implementation are able to
process traditional C, ANSI C, and C++. The latter feature, however,
is just a first attempt, i.e., most C++ sources should be handled
satisfactory, but some C++ constructions may yield unpleasant results
in typesetting by CWEAVE. If you encounter problems, send a report to
[e-mail]. Note that CTANGLE always uses a default
extension .c for its output file; this may not be appropriate for C++
compilers, but you can work around this by supplying a third argument
in the command line (see cwebman).

9. You can define a font for comments in the C part of the modules by means
of the \cmntfont macro. It defaults to \tenss, i.e., ten-point sans-serif;
if you don't like this, say, e.g.,

  \let\cmntfont=\tenrm

to get a ten-point roman comment font or whatever. This command should be
placed in the limbo section of your sources or in your own version of
ccwebmac.tex.